ScrollingList

Kind of class:class
Inherits from:CoreList < UIComponent < MovieClip
Classpath:gfx.controls.ScrollingList
File last modified:Wednesday, 30 June 2010, 09:09:04
The ScrollingList is a list component that can scroll its elements. It can instantiate list items by itself or use existing list items on the stage. A ScrollIndicator or ScrollBar component can also be attached to this list component to provide scoll feedback and control. This component is populated via a DataProvider. The dataProvider is assigned via code, as shown in the example below:
scrollingList.dataProvider = ["item1", "item2", "item3", "item4", ];

Inspectable Properties
A MovieClip that derives from the ScrollingList component will have the following inspectable properties:
  • visible: Hides the component if set to false. This does not hide the attached scrollbar or any external list item renderers.
  • disabled: Disables the component if set to true. This does disable both the attached scrollbar and the list items (both internally created and external renderers).
  • itemRenderer: The symbol name of the ListItemRenderer. Used to create list item instances internally. Has no effect if the rendererInstanceName property is set.
  • rendererInstanceName: Prefix of the external list item renderers to use with this ScrollingList component. The list item instances on the stage must be prefixed with this property value. If this property is set to the value ‘r’, then all list item instances to be used with this component must have the following values: ‘r1’, ‘r2’, ‘r3’,… The first item should have the number 1.
  • scrollBar: Instance name of a ScrollBar component on the stage or a symbol name. If an instance name is specified, then the ScrollingList will hook into that instance. If a symbol name is specified, an instance of the symbol will be created by the ScrollingList.
  • margin: The margin between the boundary of the list component and the list items created internally. This value has no effect if the rendererInstanceName property is set. This margin also affects the automatically generated scrollbar.
  • rowHeight: The height of list item instances created internally. This value has no effect if the rendererInstanceName property is set.
  • paddingTop:Extra padding at the top for the list items. This value has no effect if the rendererInstanceName property is set. Does not affect the automatically generated scrollbar.
  • paddingBottom:Extra padding at the bottom for the list items. This value has no effect if the rendererInstanceName property is set. Does not affect the automatically generated scrollbar.
  • paddingLeft:Extra padding on the left side for the list items. This value has no effect if the rendererInstanceName property is set. Does not affect the automatically generated scrollbar.
  • paddingRight:Extra padding on the right side for the list items. This value has no effect if the rendererInstanceName property is set. Does not affect the automatically generated scrollbar.
  • thumbOffsetTop:Scrollbar thumb top offset. This property has no effect if the list does not automatically create a scrollbar instance.
  • thumbOffsetBottom:Scrollbar thumb bottom offset. This property has no effect if the list does not automatically create a scrollbar instance.
  • thumbSizeFactor:Page size factor for the scrollbar thumb. A value greater than 1.0 will increase the thumb size by the given factor. This positive value has no effect if a scrollbar is not attached to the list.
  • enableInitCallback: If set to true, _global.CLIK_loadCallback() will be fired when a component is loaded and _global.CLIK_unloadCallback will be called when the component is unloaded. These methods receive the instance name, target path, and a reference the component as parameters. _global.CLIK_loadCallback and _global.CLIK_unloadCallback should be overriden from the game engine using GFx FunctionObjects.
  • soundMap: Mapping between events and sound process. When an event is fired, the associated sound process will be fired via _global.gfxProcessSound, which should be overriden from the game engine using GFx FunctionObjects.
States
The ScrollingList component supports three states based on its focused and disabled properties.
  • default or enabled state.
  • focused state, that typically highlights the component’s border area.
  • disabled state.
Events
All event callbacks receive a single Object parameter that contains relevant information about the event. The following properties are common to all events.
  • type: The event type.
  • target: The target that generated the event.
The events generated by the ScrollingList component are listed below. The properties listed next to the event are provided in addition to the common properties.
  • show: The component’s visible property has been set to true at runtime.
  • hide: The component’s visible property has been set to false at runtime.
  • focusIn: The component has received focus.
  • focusOut: The component has lost focus.
  • change: The selected index has changed.
    • index: The new selected index. Number type. Values 0 to number of list items minus 1.
  • itemPress: The list item has been pressed down.
    • renderer: The list item that was pressed. CLIK Button type.
    • item: The data associated with the list item. This value is retrieved from the list’s DataProvider. AS2 Object type.
    • index: The index of the list item relative to the list’s DataProvider. Values 0 to number of list items minus 1.
    • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.
  • itemClick: A list item has been clicked.
    • renderer: The list item that was clicked. CLIK Button type.
    • item: The data associated with the list item. This value is retrieved from the list’s DataProvider. AS2 Object type.
    • index: The index of the list item relative to the list’s DataProvider. Values 0 to number of list items minus 1.
    • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.
  • itemDoubleClick: The mouse cursor has been double clicked.
    • renderer: The list item was double clicked. CLIK Button type.
    • item: The data associated with the list item. This value is retrieved from the list’s DataProvider. AS2 Object type.
    • index: The index of the list item relative to the list’s DataProvider. Values 0 to number of list items minus 1.
    • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.
  • itemRollOver: The mouse cursor has rolled over a list item.
    • renderer: The list item that was rolled over.CLIK Button type.
    • item: The data associated with the list item. This value is retrieved from the list’s DataProvider. AS2 Object type.
    • index: The index of the list item relative to the list’s DataProvider. Values 0 to number of list items minus 1.
    • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.
  • itemRollOut: The mouse cursor has rolled out of a list item.
    • renderer: The list item that was rolled out of.CLIK Button type.
    • item: The data associated with the list item. This value is retrieved from the list’s DataProvider. AS2 Object type.
    • index: The index of the list item relative to the list’s DataProvider.Values 0 to number of list items minus 1.
    • controllerIdx: The index of the mouse cursor used to generate the event (applicable only for multi-mouse-cursor environments). Number type. Values 0 to 3.

Summary


Constructor
Instance properties
Instance properties inherited from CoreList
_dataProvider _itemRenderer _labelField _labelFunction _selectedIndex availableHeight availableWidth container dataProvider deferredScrollIndex externalRenderers inspectableRendererInstanceName itemRenderer labelField labelFunction rendererInstanceName renderers selectedIndex soundMap
Instance properties inherited from UIComponent
__height __width _disabled _displayFocus _focused addEventListener cleanUpEvents disabled dispatchEvent displayFocus enableInitCallback focused focusHandlerReference focusTarget hasEventListener height initialized invalidationIntervalID removeAllEventListeners removeEventListener sizeIsInvalid soundMap visible width
Class methods
Class methods inherited from UIComponent
createInstance
Instance methods
  • scrollToIndex
    • Scroll the list to the specified index.
  • invalidateData
    • The current data has become invalid, either by a data change, or a display change such as scrolling.
  • handleInput
    • Handle input from the game, via controllers or keyboard.
Instance methods inherited from CoreList
configUI createItemRenderer createItemRenderers dispatchItemEvent draw drawLayout drawRenderers getRendererAt handleItemClick invalidateData itemToLabel onDataChange resetRenderers scrollToIndex setRendererList setUpRenderer toString
Instance methods inherited from UIComponent
changeFocus configUI dispatchEventAndSound dispatchEventToGame draw handleInput initSize invalidate onLoad onLoadImpl onMouseWheel onUnload scrollWheel setSize toString validateNow

Constructor

ScrollingList

function ScrollingList (
)

The constructor is called when a ScrollingList or a sub-class of ScrollingList is instantiated on stage or by using attachMovie() in ActionScript. This component can not be instantiated using new syntax. When creating new components that extend ScrollingList, ensure that a super() call is made first in the constructor.

Instance properties

autoRowCount

autoRowCount:Boolean = false
(read,write)

Determines if the "rowCount" property is applied directly, or converted by the component. ScrollingList does not use autoRowCount, but includes it for consistency.

availableWidth

availableWidth:Number
(read)

disabled

disabled:Boolean
(read,write)

Component metadata:
    Inspectable
    defaultValue:
    "false"
    verbose:
    "1"

    rowCount

    rowCount:Number
    (read,write)

    The amount of visible rows. Setting this property will immediately change the height of the component to accomodate the specified amount of rows. The rowCount property is not stored or maintained.

    rowHeight

    rowHeight:Number
    (read,write)

    The height of each item in the list. When set to null or 0, the default height of the renderer symbol is used.
    Component metadata:
      Inspectable
      defaultValue:
      "0"

      scrollBar

      scrollBar:Object
      (read,write)

      The component to use to scroll the list. The scrollBar can be set as a library linkage ID, an instance name on the stage relative to the component, or a reference to an existing ScrollBar elsewhere in the application. The automatic behaviour in this component only supports a vertical scrollBar, positioned on the top right, the entire height of the component.
      See also:

      scrollPosition

      scrollPosition:Number
      (read,write)

      The vertical scroll position of the list.

      selectedIndex

      selectedIndex:Number
      (read,write)

      The selected index of the dataProvider. The itemRenderer at the selectedIndex will be set to selected=true.

      wrapping

      wrapping:String = "normal"
      (read,write)

      Determines how focus "wraps" when the end or beginning of the component is reached.
      • "normal": The focus will leave the component when it reaches the end of the data
      • "wrap": The selection will wrap to the beginning or end.
      • "stick": The selection will stop when it reaches the end of the data.

      Instance methods

      handleInput

      function handleInput (
      details:InputDetails, pathToFocus:Array) : Boolean

      Handle input from the game, via controllers or keyboard. The default handleInput will handle standalone and composite components.
      Parameters:
      details :
      An InputDetails object containing details from the interaction.
      pathToFocus:
      A list of children in the focus path that are below this component. Components are responsible for calling handleInput() on the next component in the pathToFocus unless they choose to intercept the call.
      Overrides:

      invalidateData

      function invalidateData (
      ) : Void

      The current data has become invalid, either by a data change, or a display change such as scrolling. It is up to the sub-classes to determine the behaviour.
      Overrides:

      scrollToIndex

      function scrollToIndex (
      index:Number) : Void

      Scroll the list to the specified index. If the index is currently visible, the position will not change. The scroll position will only change the minimum amount it has to to display the item at the specified index.
      Parameters:
      index:
      The index to scroll to.
      Overrides: